JBoss Web Subsystem Configuration
The extension's module org.jboss.as.web *is replaced by module *org.wildfly.extension.undertow, while the subsystem configuration namespace urn:jboss:domain:web:* is replaced by urn:jboss:domain:undertow:3.0.
The XML configuration of the new subsystem is relatively different. Consider the following example of the JBoss Web subsystem configuration, containing all valid elements and attributes:
<?xml version="1.0" encoding="UTF-8"?>
<subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="true" default-session-timeout="30" instance-id="foo">
<configuration>
<static-resources listings="true"
sendfile="1000"
file-encoding="utf-8"
read-only="true"
webdav="false"
secret="secret"
max-depth="5"
disabled="false"
/>
<jsp-configuration development="true"
disabled="false"
keep-generated="true"
trim-spaces="true"
tag-pooling="true"
mapped-file="true"
check-interval="20"
modification-test-interval="1000"
recompile-on-fail="true"
smap="true"
dump-smap="true"
generate-strings-as-char-arrays="true"
error-on-use-bean-invalid-class-attribute="true"
scratch-dir="/some/dir"
source-vm="1.7"
target-vm="1.7"
java-encoding="utf-8"
x-powered-by="true"
display-source-fragment="true" />
<mime-mapping name="ogx" value="application/ogg" />
<welcome-file>titi</welcome-file>
</configuration>
<connector name="http" scheme="http"
protocol="HTTP/1.1"
socket-binding="http"
enabled="true"
enable-lookups="false"
proxy-binding="reverse-proxy"
max-post-size="2097153"
max-save-post-size="512"
redirect-binding="https"
max-connections="300"
secure="false"
executor="some-executor"
/>
<connector name="https" scheme="https" protocol="HTTP/1.1" secure="true" socket-binding="https">
<ssl certificate-key-file="${file-base}/server.keystore"
ca-certificate-file="${file-base}/jsse.keystore"
key-alias="test"
password="changeit"
cipher-suite="SSL_RSA_WITH_3DES_EDE_CBC_SHA"
protocol="SSLv3"
verify-client="true"
verify-depth="3"
certificate-file="certificate-file.ext"
ca-revocation-url="https://example.org/some/url"
ca-certificate-password="changeit"
keystore-type="JKS"
truststore-type="JKS"
session-cache-size="512"
session-timeout="3000"
ssl-protocol="RFC4279"
/>
</connector>
<connector name="http-vs" scheme="http" protocol="HTTP/1.1" socket-binding="http" >
<virtual-server name="vs1" />
<virtual-server name="vs2" />
</connector>
<virtual-server name="default-host" enable-welcome-root="true" default-web-module="foo.war">
<alias name="localhost" />
<alias name="example.com" />
<access-log resolve-hosts="true" extended="true" pattern="extended" prefix="prefix" rotate="true" >
<directory relative-to="jboss.server.base.dir" path="toto" />
</access-log>
<rewrite name="myrewrite" pattern="^/helloworld(.*)" substitution="/helloworld/test.jsp" flags="L" />
<rewrite name="with-conditions" pattern="^/helloworld(.*)" substitution="/helloworld/test.jsp" flags="L" >
<condition name="https" pattern="off" test="%{HTTPS}" flags="NC"/>
<condition name="user" test="%{USER}" pattern="toto" flags="NC"/>
<condition name="no-flags" test="%{USER}" pattern="toto"/>
</rewrite>
<sso reauthenticate="true" domain="myDomain" cache-name="myCache"
cache-container="cache-container" http-only="true"/>
</virtual-server>
<virtual-server name="vs1" />
<virtual-server name="vs2" />
<valve name="myvalve" module="org.jboss.some.module" class-name="org.jboss.some.class" enabled="true">
<param param-name="param-name" param-value="some-value"/>
</valve>
<valve name="accessLog" module="org.jboss.as.web" class-name="org.apache.catalina.valves.AccessLogValve">
<param param-name="prefix" param-value="myapp_access_log." />
<param param-name="suffix" param-value=".log" />
<param param-name="rotatable" param-value="true" />
<param param-name="fileDateFormat" param-value="yyyy-MM-dd" />
<param param-name="pattern" param-value="common" />
<param param-name="directory" param-value="${jboss.server.log.dir}" />
<param param-name="resolveHosts" param-value="false"/>
<param param-name="conditionIf" param-value="log-enabled"/>
</valve>
<valve name="request-dumper" module="org.jboss.as.web" class-name="org.apache.catalina.valves.RequestDumperValve"/>
<valve name="remote-addr" module="org.jboss.as.web" class-name="org.apache.catalina.valves.RemoteAddrValve">
<param param-name="allow" param-value="127.0.0.1,127.0.0.2" />
<param param-name="deny" param-value="192.168.1.20" />
</valve>
<valve name="crawler" class-name="org.apache.catalina.valves.CrawlerSessionManagerValve" module="org.jboss.as.web" >
<param param-name="sessionInactiveInterval" param-value="1" />
<param param-name="crawlerUserAgents" param-value="Google" />
</valve>
<valve name="proxy" class-name="org.apache.catalina.valves.RemoteIpValve" module="org.jboss.as.web" >
<param param-name="internalProxies" param-value="192\.168\.0\.10|192\.168\.0\.11" />
<param param-name="remoteIpHeader" param-value="x-forwarded-for" />
<param param-name="proxiesHeader" param-value="x-forwarded-by" />
<param param-name="trustedProxies" param-value="proxy1|proxy2" />
</valve>
</subsystem>
FIXME compare with Undertow, list unsupported features
It's possible to do a migration of the legacy subsystem configuration, and related persisted data. , by invoking the legacy’s subsystem’s migrate operation, using the CLI management client:
There is also a describe-migration operation that returns a list of all the management operations that are performed to migrate from the legacy subsystem to the new one:
/subsystem=web:describe-migration
Both migrate and describe-migration will also display a list of migration-warnings if there are some resource or attributes that can not be migrated automatically. The following is a list of these warnings:
-
Could not migrate resource X
This warning means that mentioned resource configuration is not supported and won't be included in the new subsystem configuration. As a result of that admin must be aware that any behaviour implied by those resources would be inexistent. Admin has to check whether subsystem is able to operate correctly without that behaviour on the new server.
FIXME must document which are the resources that trigger this
-
Could not migrate attribute X from resource Y.
This warning means that mentioned resource configuration property is not supported and won't be included in the new subsystem configuration. As a result of that admin must be aware that any behaviour implied by those properties would be inexistent. Admin has to check whether subsystem is able to operate correctly without that behaviour on the new server.
FIXME must document which are the properties that trigger this
-
Could not migrate SSL connector as no SSL config is defined
-
Could not migrate verify-client attribute %s to the Undertow equivalent
-
Could not migrate verify-client expression %s
-
Could not migrate valve X
This warning means that mentioned valve configuration is not supported and won't be included in the new subsystem configuration. As a result of that admin must be aware that any behaviour implied by those resources would be inexistent. Admin has to check whether subsystem is able to operate correctly without that behaviour on the new server. This warning may happen for :
-
org.apache.catalina.valves.RemoteAddrValve : must have at least one allowed or denied value.
-
org.apache.catalina.valves.RemoteHostValve : must have at least one allowed or denied value.
-
org.apache.catalina.authenticator.BasicAuthenticator
-
org.apache.catalina.authenticator.DigestAuthenticator
-
org.apache.catalina.authenticator.FormAuthenticator
-
org.apache.catalina.authenticator.SSLAuthenticator
-
org.apache.catalina.authenticator.SpnegoAuthenticator
-
custom valves
-
Could not migrate attribute X from valve Y
This warning means that mentioned valve configuration property is not supported and won't be included in the new subsystem configuration. As a result of that admin must be aware that any behaviour implied by those properties would be inexistent. Admin has to check whether subsystem is able to operate correctly without that behaviour on the new server. This warning may happen for :
-
org.apache.catalina.valves.AccessLogValve : if you use the following parameters resolveHosts, fileDateFormat, renameOnRotate, encoding, locale, requestAttributesEnabled, buffered.
-
org.apache.catalina.valves.ExtendedAccessLogValve : if you use the following parameters resolveHosts, fileDateFormat, renameOnRotate, encoding, locale, requestAttributesEnabled, buffered.
-
org.apache.catalina.valves.RemoteIpValve:
-
if remoteIpHeader is defined and isn't set to "x-forwarded-for".
-
if protocolHeader is defined and isn't set to "x-forwarded-proto".
-
if you use the following parameters httpServerPort and httpsServerPort .
Also, please note that Undertow doesn't support JBoss Web valves, but some of these may be migrated to Undertow handlers, and JBoss Web subsystem’s migrate operation do that too.
Here is a list of those valves and their corresponding Undertow handler:
Valve
|
Handler
|
org.apache.catalina.valves.AccessLogValve
|
io.undertow.server.handlers.accesslog.AccessLogHandler
|
org.apache.catalina.valves.ExtendedAccessLogValve
|
io.undertow.server.handlers.accesslog.AccessLogHandler
|
org.apache.catalina.valves.RequestDumperValve
|
io.undertow.server.handlers.RequestDumpingHandler
|
org.apache.catalina.valves.RewriteValve
|
io.undertow.server.handlers.SetAttributeHandler
|
org.apache.catalina.valves.RemoteHostValve
|
io.undertow.server.handlers.AccessControlListHandler
|
org.apache.catalina.valves.RemoteAddrValve
|
io.undertow.server.handlers.IPAddressAccessControlHandler
|
org.apache.catalina.valves.RemoteIpValve
|
io.undertow.server.handlers.ProxyPeerAddressHandler
|
org.apache.catalina.valves.StuckThreadDetectionValve
|
io.undertow.server.handlers.StuckThreadDetectionHandler
|
org.apache.catalina.valves.CrawlerSessionManagerValve
|
io.undertow.servlet.handlers.CrawlerSessionManagerHandler
|
The org.apache.catalina.valves.JDBCAccessLogValve can't be automatically migrated to io.undertow.server.handlers.JDBCLogHandler as the expectations differ.
The migration can be done manually thought :
-
create the driver module and add the driver to the list of available drivers
-
create a datasource pointing to the database where the log entries are going to be stored
-
add an expression-filter definition with the following expression: "jdbc-access-log(datasource='datasource-jndi-name')
<valve name="jdbc" module="org.jboss.as.web" class-name="org.apache.catalina.valves.JDBCAccessLogValve">
<param param-name="driverName" param-value="com.mysql.jdbc.Driver" />
<param param-name="connectionName" param-value="root" />
<param param-name="connectionPassword" param-value="password" />
<param param-name="connectionURL" param-value="jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull" />
<param param-name="format" param-value="combined" />
</valve>
should become:
<subsystem xmlns="urn:jboss:domain:datasources:1.2">
<datasources>
<datasource jndi-name="java:jboss/datasources/accessLogDS" pool-name="ccessLogDS" enabled="true" use-java-context="true">
<connection-url>jdbc:mysql://localhost:3306/wildfly?zeroDateTimeBehavior=convertToNull</connection-url>
<driver>mysql</driver>
<security>
<user-name>root</user-name>
<password>password</password>
</security>
</datasource>
...
<drivers>
<driver name="mysql" module="com.mysql">
<driver-class>com.mysql.jdbc.Driver</driver-class>
</driver>
...
</drivers>
</datasources>
</subsystem>
...
<subsystem xmlns="urn:jboss:domain:undertow:3.1" default-virtual-host="default-virtual-host" default-servlet-container="myContainer"
default-server="some-server" instance-id="some-id" statistics-enabled="true">
...
<server name="some-server" default-host="other-host" servlet-container="myContainer">
...
<host name="other-host" alias="www.mysite.com, ${prop.value:default-alias}" default-web-module="something.war" disable-console-redirect="true">
<location name="/" handler="welcome-content" />
<filter-ref name="jdbc-access"/>
</host>
</server>
...
<filters>
<expression-filter name="jdbc-access" expression="jdbc-access-log(datasource='java:jboss/datasources/accessLogDS')" />
...
</filters>
</subsystem>
Please note that any custom valve won't be migrated at all and will just be removed from the configuration.
Also the authentication related valves are to be replaced by Undertow authentication mechanisms, and this have to be done manually.
FIXME how this last “manual” replacement is done? Need whole process documented and concrete example
WebSockets
In AS7, to use WebSockets, you had to configure the 'http' connector in the web subsystem of the server configuration file to use the NIO2 protocol. The following is an example of the Management CLI command to configure WebSockets in the previous releases.
/subsystem=web/connector=http/:write-attribute(name=protocol,value=org.apache.coyote.http11.Http11NioProtocol)
WebSockets are a requirement of the Java EE 7 specification and the default configuration is included in WildFly. More complex WebSocket configuration is done in the servlet-container of the undertow subsystem of the server configuration file.
You no longer need to configure the server for default WebSocket support.
FIXME isn’t <websockets /> required for that?